None exec_jwst_flat_field_miri_test

JWST Pipeline Validation Testing notebook: flat_field step with MIRI Imaging

Instruments Affected: NIRCam, NIRSpec, NIRISS, MIRI, FGS

Introduction

This test is designed to test the flat_field step in the calwebb_image2 pipeline. This step retrieves the correct flat field reference file and divides the data by the reference file. The SCI extension of the reference file is divided into the SCI array of the science image. The DQ plane of the reference file is combined with the DQ plane of the science file.

Error calculation: The VAR_POISSON and VAR_RNOISE variance arrays of the science exposure are divided by the square of the flat-field value for each pixel. A flat-field variance array, VAR_FLAT, is created from the science exposure and flat-field reference file data using the following formula:

var_flat = SCI array ^ 2 / flat SCI array ^ 2 * flat err array ^2

The total ERR array in the science exposure is updated as the square root of the quadratic sum of VAR_POISSON, VAR_RNOISE, and VAR_FLAT.

Description of the steps applied:

Documentation

For more information on the pipeline step visit the links below.

The pipeline documentation can be found here: https://jwst-pipeline.readthedocs.io/en/latest/

The pipeline code is available on GitHub: https://github.com/spacetelescope/jwst

Test Description

This notebook processes an image through calwebb_image2 (calwebb_detector1 is optional) and examines the output of the flat_field step. The steps are as follow:

1) Retrieve data.

2) Run output of calwebb_detector1 through the flat_field step in calwebb_image2. Visualize the sci arrays of the data before and after the flat_field step is applied.

3) Get flat field reference file. Look at the sci array of the flat_field reference file.

4) Compare the flat field reference file with the rate/cal image ratio and check that they are the same.

5) Look at the ERR arrays of the science data before and after the step is run, and compare to the flat_field reference file ERR array to be sure there is no unexpected pattern seen. Check that a new extension (var_flat) has been added to the output data.

6) Check that the DQ flags were applied as expected.

Data used

The data used in this test is a simulated MIRI image created using MIRISim. The documentation for MIRISim can be found here: https://wiki.miricle.org/bin/view/Public/MIRISim_Public

Set up import statements

Software imports:

Read in data from artifactory (or Box)

Read in input image as JWST data model

Display the rate (slope) file that is output of calwebb_detector1

Run output of calwebb_detector1 through the flat field step

Display the calibrated data that is output of calwebb_image2

Calculate the rate/cal image ratio

Display ratio image

The ratio of the images calculated above should be comparable to the flat field reference file science extension.

Get flat_field reference file

Display flat field reference file data

Compare flat field reference file with the rate/cal image ratio and check that they are equal

Since the step sets any flat field values to 1 where the DQ array lists the pixel as DO_NOT_USE, only a masked version of the images should be compared to the flat. Find regions where dq values are not marked as DO_NOT_USE and compare the good regions.

View the ratio image divided by the flat field ((rate / flat_fielded image) / flat field reference file)

The values of this image should be around 1.0. The flat fielded science image results from dividing the rate image by the flat field reference file image. So the ratio of the rate image divided by the flat_fielded image should equal the flat field reference file, meaning that ratio should equal 1.0.

Check that min and max values of ratio image divided by the flat are 1.0

Check ERR arrays

There should be a new ERR array (var_flat) attached.

Check that var_flat extension was added to data after flat field step was run

Look at error arrays before and after flat field step to see if there are any unexplained changes

Check DQ flagging

Any pixel flagged as NON_SCIENCE should also be flagged as DO_NOT_USE. Check if this is in place in both the input reference file and for the output science file of the calwebb_image2 pipeline. If there are no assert errors, the test below passes.

Look at the dq planes to see how they change.

The dq planes shown below show the rate file before the flat field step, the reference file dq plane, and the dq plane after the flat field step is applied.

The regions marked with white have been set as 'DO_NOT_USE' in the dq plane. The images below should show that the 4QPM regions are marked as DO_NOT_USE by the flat field step. The rate image dq plane does not remove the 4QPM, but the flat field dq plane and the cal dq plane should both have the 4QPM regions marked as DO_NOT_USE.

Take a look at the dq plane of the flat field reference file.

The dq definitions in the flat field file are as follows (from the dq_def extention)

    Value    DQ Name
        1  DO_NOT_USE
        2  NON_SCIENCE
        4  UNRELIABLE_FLAT
        8  CDP_PARTIAL_DATA
       16  CDP_LOW_QUAL
       32  CDP_UNRELIABLE_ERROR
       64  NO_FLAT_FIELD
      128  DIFF_PATTERN

If the pixel has an odd numbered value, it has been combined with the value 'DO_NOT_USE', and is not applied in the division of the science data by the flat. These 'bad' pixels are flagged in the following image by being shown in white. The purple pixels have values of zero, which indicate they are good science pixels.

Take a look at what portion of the flat fielded image will be masked out in combined (image3 pipeline) data

Take the masked NaN region shown above and apply it to the flat fielded image to see what portion of the image will be masked out once calwebb_image3 is run and the DO_NOT_USE pixels are masked out.

Passing criteria

If none of the assert messages or error messages print throughout the notebook and the sci ratio comparison gives values near 1.0, this test passes. The images are mostly for quick checks that nothing looks unusual or out of place.

About this Notebook

Author: T. Temim and M. Cracraft, INS/MIRI
Updated On: 05/11/2021